/**
 * @file buffer_utils.h
 * @brief 通用缓冲区处理工具函数
 * @author 电网104协议开发团队
 * @date 2024
 */

#ifndef BUFFER_UTILS_H
#define BUFFER_UTILS_H

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 通用错误码定义 ==================== */

typedef enum {
    BUFFER_SUCCESS = 0,           /* 成功 */
    BUFFER_ERROR_NULL_POINTER,    /* 空指针错误 */
    BUFFER_ERROR_INVALID_PARAM,   /* 无效参数 */
    BUFFER_ERROR_OUT_OF_BOUNDS,   /* 越界错误 */
    BUFFER_ERROR_INSUFFICIENT_DATA /* 数据不足 */
} buffer_error_t;

/* ==================== 字节序转换函数 ==================== */

/**
 * @brief 16位整数字节序转换(主机序<->网络序)
 * @param value 16位整数值
 * @return 转换后的值
 */
uint16_t htons_16(uint16_t value);
uint16_t ntohs_16(uint16_t value);

/**
 * @brief 32位整数字节序转换(主机序<->网络序)
 * @param value 32位整数值
 * @return 转换后的值
 */
uint32_t htonl_32(uint32_t value);
uint32_t ntohl_32(uint32_t value);

/**
 * @brief 64位整数字节序转换(主机序<->网络序)
 * @param value 64位整数值
 * @return 转换后的值
 */
uint64_t htonll_64(uint64_t value);
uint64_t ntohll_64(uint64_t value);

/**
 * @brief 32位浮点数字节序转换(主机序<->网络序)
 * @param value 32位浮点数值
 * @return 转换后的值
 */
float htonf_32(float value);
float ntohf_32(float value);

/**
 * @brief 64位浮点数字节序转换(主机序<->网络序)
 * @param value 64位浮点数值
 * @return 转换后的值
 */
double htond_64(double value);
double ntohd_64(double value);

/* ==================== 缓冲区读写函数 ==================== */

/**
 * @brief 安全读取8位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 输出值
 * @return 缓冲区错误码
 */
buffer_error_t buffer_read_u8(const uint8_t* buffer, size_t offset, uint8_t* value);

/**
 * @brief 安全读取16位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 输出值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_read_u16(const uint8_t* buffer, size_t offset, uint16_t* value, int big_endian);

/**
 * @brief 安全读取32位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 输出值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_read_u32(const uint8_t* buffer, size_t offset, uint32_t* value, int big_endian);

/**
 * @brief 安全读取64位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 输出值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_read_u64(const uint8_t* buffer, size_t offset, uint64_t* value, int big_endian);

/**
 * @brief 安全写入8位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 要写入的值
 * @return 缓冲区错误码
 */
buffer_error_t buffer_write_u8(uint8_t* buffer, size_t offset, uint8_t value);

/**
 * @brief 安全写入16位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 要写入的值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_write_u16(uint8_t* buffer, size_t offset, uint16_t value, int big_endian);

/**
 * @brief 安全写入32位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 要写入的值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_write_u32(uint8_t* buffer, size_t offset, uint32_t value, int big_endian);

/**
 * @brief 安全写入64位数据
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 要写入的值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_write_u64(uint8_t* buffer, size_t offset, uint64_t value, int big_endian);

/**
 * @brief 安全读取32位浮点数
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 输出值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_read_f32(const uint8_t* buffer, size_t offset, float* value, int big_endian);

/**
 * @brief 安全写入32位浮点数
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param value 要写入的值
 * @param big_endian 是否大端序
 * @return 缓冲区错误码
 */
buffer_error_t buffer_write_f32(uint8_t* buffer, size_t offset, float value, int big_endian);

/* ==================== 缓冲区操作函数 ==================== */

/**
 * @brief 安全复制缓冲区数据
 * @param dest 目标缓冲区
 * @param src 源缓冲区
 * @param size 复制大小
 * @return 缓冲区错误码
 */
buffer_error_t buffer_copy(uint8_t* dest, const uint8_t* src, size_t size);

/**
 * @brief 安全设置缓冲区数据
 * @param buffer 缓冲区
 * @param value 设置值
 * @param size 设置大小
 * @return 缓冲区错误码
 */
buffer_error_t buffer_set(uint8_t* buffer, uint8_t value, size_t size);

/**
 * @brief 计算缓冲区校验和
 * @param buffer 缓冲区
 * @param size 缓冲区大小
 * @return 校验和值
 */
uint8_t buffer_checksum(const uint8_t* buffer, size_t size);

/**
 * @brief 计算缓冲区CRC16校验
 * @param buffer 缓冲区
 * @param size 缓冲区大小
 * @return CRC16值
 */
uint16_t buffer_crc16(const uint8_t* buffer, size_t size);

/**
 * @brief 计算缓冲区CRC32校验
 * @param buffer 缓冲区
 * @param size 缓冲区大小
 * @return CRC32值
 */
uint32_t buffer_crc32(const uint8_t* buffer, size_t size);

/* ==================== 缓冲区验证函数 ==================== */

/**
 * @brief 验证缓冲区边界
 * @param buffer 缓冲区
 * @param offset 偏移量
 * @param size 数据大小
 * @param buffer_size 缓冲区总大小
 * @return 缓冲区错误码
 */
buffer_error_t buffer_validate_bounds(const uint8_t* buffer, size_t offset, size_t size, size_t buffer_size);

/**
 * @brief 验证缓冲区指针
 * @param buffer 缓冲区指针
 * @return 缓冲区错误码
 */
buffer_error_t buffer_validate_pointer(const uint8_t* buffer);

#ifdef __cplusplus
}
#endif

#endif /* BUFFER_UTILS_H */
